fix(cli): fix join dropping non-string x-* path extension properties by nonchan7720 · Pull Request #2949 · Redocly/redocly-cli

nonchan7720 · 2026-07-13T16:41:20Z

What/Why/How?

Fixes join silently dropping non-string x-* extension properties defined directly under a path item (e.g.
paths./pets/{petId}.x-foo: true).

collectPaths only merged path-level extensions when their value was a string, via collectPathStringFields. Non-string values
(booleans, objects, arrays, numbers) were never copied into the joined document.

collectPathExtension now handles every non-string x-* field on a path item: it copies the value into the joined path the first
time it's seen, and logs a warning instead of silently overwriting when two source documents provide different values for the same
field.

Reference

Fixes #1574

Testing

Added a path extensions test group to join.test.ts with fixtures in documents.ts covering:

merging a non-string x-* path extension when both source documents agree on the value
logging a warning when the values conflict

Verified against the pre-fix implementation that both new tests fail without this change.

Screenshots (optional)

N/A — CLI behavior change only.

Check yourself

This PR follows the contributing guide
All new/updated code is covered by tests
Core code changed? - Tested with other Redocly products (internal contributions only) — N/A, packages/cli only
New package installed? - Tested in different environments (browser/node) — N/A
Documentation update has been considered — no doc change needed, this restores documented merge behavior
Changeset added — still missing, run npx changeset before merging (@redocly/cli, patch)

Security

The security impact of the change has been considered — object merge over already-parsed/trusted document data, no new external
input surface
Code follows company security practices and guidelines

Note

Low Risk
Scoped CLI merge logic fix with tests; no new input surface beyond existing parsed OpenAPI documents.

Overview
Fixes join silently dropping path-level x-* extensions when values are not strings (objects, booleans, arrays, etc.).

In collect-paths.ts, path item fields are now merged when the value is a string or the key starts with x-, so those extensions are copied into the joined document like string fields (summary, description). Conflict detection uses dequal instead of !==, so object extensions with the same content merge without a warning; differing values keep the first document’s value and emit logger.warn.

Adds a path extensions test group and fixtures for matching object x-metadata, conflicting values, and objects with different keys. Includes a patch changeset for @redocly/cli.

^{Reviewed by Cursor Bugbot for commit 1fa9e74. Bugbot is set up for automated code reviews on this repo. Configure here.}

changeset-bot · 2026-07-13T16:41:26Z

🦋 Changeset detected

Latest commit: 1fa9e74

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@redocly/cli	Patch
@redocly/openapi-core	Patch
@redocly/respect-core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Clarified the fix for join extension property to specify that it addresses non-string x-* path extension properties.

github-actions · 2026-07-14T16:18:06Z

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
cli-latest	▓ 1.01x ± 0.02	▓ 1.01x ± 0.01	▓ 1.01x ± 0.02
cli-next	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)

adamaltman · 2026-07-16T17:00:14Z

+        .mockImplementationOnce(() =>
+          Promise.resolve({
+            source: { absoluteRef: 'ref-b' },
+            parsed: anotherPathWithDifferentObjectExtension,


What if the object had different keys though? Like a.yaml has owner and b.yaml has team?

A warning log is being output.
I think we'll just have to handle this the same way we do other standard items.

If this part overlaps, it means the paths also overlap.

@nonchan7720 Please add a test for this case { owner: 'team-a' } and { team: 'x' }.

kanoru3101

Thanks for the contribution. Checked it out locally — works as expected, non-string x-* path extensions now merge the same way as regular path-level fields (first one wins, warning on conflict).

Left a few comments.

kanoru3101 · 2026-07-17T12:32:42Z

+        .mockImplementationOnce(() =>
+          Promise.resolve({
+            source: { absoluteRef: 'ref-b' },
+            parsed: anotherPathWithDifferentObjectExtension,


@nonchan7720 Please add a test for this case { owner: 'team-a' } and { team: 'x' }.

Co-authored-by: Viktor Sydor <31951646+kanoru3101@users.noreply.github.com>

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 310638c. Configure here.}

RomanHotsiy

LGTM, left one simplification comment

RomanHotsiy · 2026-07-18T00:38:37Z

-        if (typeof pathItem[field] === 'string') {
+        if (
+          typeof pathItem[field] === 'string' ||
+          (field.startsWith('x-') && typeof pathItem[field] !== 'string')


Suggested change

(field.startsWith('x-') && typeof pathItem[field] !== 'string')

(field.startsWith('x-'))

fixed.
5b7a1cc

kanoru3101

LGTM

Co-authored-by: Viktor Sydor <31951646+kanoru3101@users.noreply.github.com>

nonchan7720 · 2026-07-20T12:19:28Z

@RomanHotsiy @kanoru3101

What else do I need to do to get this PR merged? 🙏

Daryna-del · 2026-07-21T09:22:07Z

Hey @nonchan7720
Many thanks for the contribution again! There is nothing left on your side, I'm merging it, and it will be released as soon as possible in the next version.

fix: join extension property

8a20526

nonchan7720 added 2 commits July 14, 2026 01:59

fix collectPathExtension

9c2f824

test: cover non-string x-* path extension merging in join

489b31e

nonchan7720 changed the title ~~fix: join extension property~~ fix: Fix join dropping non-string x-* path extension properties. Jul 13, 2026

Clarify fix for join extension property

bc76fd1

Clarified the fix for join extension property to specify that it addresses non-string x-* path extension properties.

nonchan7720 marked this pull request as ready for review July 13, 2026 17:16

nonchan7720 requested review from a team as code owners July 13, 2026 17:16

nonchan7720 changed the title ~~fix: Fix join dropping non-string x-* path extension properties.~~ fix(cli): Fix join dropping non-string x-* path extension properties. Jul 13, 2026

nonchan7720 changed the title ~~fix(cli): Fix join dropping non-string x-* path extension properties.~~ fix(cli): fix join dropping non-string x-* path extension properties. Jul 14, 2026

nonchan7720 changed the title ~~fix(cli): fix join dropping non-string x-* path extension properties.~~ fix(cli): fix join dropping non-string x-* path extension properties Jul 14, 2026

adamaltman reviewed Jul 16, 2026

View reviewed changes

kanoru3101 reviewed Jul 17, 2026

View reviewed changes

Update .changeset/dull-adults-punch.md

310638c

Co-authored-by: Viktor Sydor <31951646+kanoru3101@users.noreply.github.com>

cursor Bot reviewed Jul 17, 2026

View reviewed changes

Comment thread packages/cli/src/commands/join/utils/collect-paths.ts Outdated

nonchan7720 added 2 commits July 18, 2026 00:30

test: cover x-* path extension merge when objects have different keys

229f223

refactor: merge collectPathExtension into collectPathStringFields

c3edfd1

nonchan7720 requested review from adamaltman and kanoru3101 July 17, 2026 15:38

RomanHotsiy approved these changes Jul 18, 2026

View reviewed changes

nonchan7720 and others added 2 commits July 18, 2026 10:50

refactor: simplify x-* field condition in collectPaths

5b7a1cc

Merge branch 'main' into fix_issue_1574

c3fc9fb

kanoru3101 approved these changes Jul 18, 2026

View reviewed changes

Comment thread .changeset/dull-adults-punch.md Outdated

Update .changeset/dull-adults-punch.md

b593d94

Co-authored-by: Viktor Sydor <31951646+kanoru3101@users.noreply.github.com>

nonchan7720 requested review from RomanHotsiy and kanoru3101 July 18, 2026 13:33

kanoru3101 approved these changes Jul 18, 2026

View reviewed changes

Merge branch 'main' into fix_issue_1574

1fa9e74

Daryna-del merged commit 7082ede into Redocly:main Jul 21, 2026
43 of 47 checks passed

	(field.startsWith('x-') && typeof pathItem[field] !== 'string')
	(field.startsWith('x-'))

Uh oh!

Conversation

nonchan7720 commented Jul 13, 2026 • edited by Daryna-del Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why/How?

Reference

Testing

Screenshots (optional)

Check yourself

Security

Uh oh!

changeset-bot Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Performance Benchmark (Lower is Faster)

Uh oh!

adamaltman Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

nonchan7720 Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

kanoru3101 Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

kanoru3101 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

kanoru3101 Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

RomanHotsiy left a comment

Choose a reason for hiding this comment

Uh oh!

RomanHotsiy Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

nonchan7720 Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

kanoru3101 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nonchan7720 commented Jul 20, 2026

Uh oh!

Daryna-del commented Jul 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nonchan7720 commented Jul 13, 2026 •

edited by Daryna-del

Loading

changeset-bot Bot commented Jul 13, 2026 •

edited

Loading

github-actions Bot commented Jul 14, 2026 •

edited

Loading